home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.024 < prev    next >
Encoding:
Text File  |  1992-07-15  |  13.4 KB  |  331 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIgs
  6. #24: Apple IIgs Toolbox Reference Updates
  7.  
  8. Revised by: Dave Lyons                                               May 1992
  9. Written by: Rilla Reynolds, Matt Deatherage, Dave Lyons,         October 1987
  10.             C. K. Haun & Eric Soldan
  11.  
  12. This Technical Note documents changes to the Apple IIgs Toolbox Reference
  13. manuals.  Please contact Apple II Developer Technical Support at the address
  14. listed in Apple II Technical Note #0 if you have additional corrections or
  15. suggestions for any of the Apple IIgs Toolbox documentation.
  16.  
  17. CHANGES SINCE DECEMBER 1991:  Added corrections to Dialog Manager, Menu
  18. Manager, Tool Locator, Window Manager, and Appendix E.
  19. _____________________________________________________________________________
  20.  
  21.  
  22. The current Apple IIgs Toolbox reference material is Apple IIgs Toolbox
  23. Reference, volumes 1 to 3 as well as this Technical Note.  (The Apple IIgs
  24. Toolbox Reference Update beta draft from APDA is obsolete and should not be
  25. used.)
  26.  
  27. CORRECTIONS TO VOLUME 1
  28.  
  29. DESK MANAGER--FIXAPPLEMENU CAN DIE WITH ERROR $0512
  30.  
  31. Fatal system error $0512 comes from FixAppleMenu (in the Desk Manager).  It
  32. means that one of your installed New Desk Accessories does not have a
  33. well-formed menu title string.  In particular, the required backslash (\)
  34. character was not found (make sure bit seven is off).
  35.  
  36. DIALOG MANAGER--EDITLINE ITEM VALUE
  37.  
  38. On page 6-12, the description of an editLine item value should read "Maximum
  39. length of the item text (0 to 255 characters)."
  40.  
  41. THE LIST MANAGER WANTS THE PORT SET PROPERLY
  42.  
  43. The List Manager expects the current grafPort to be set properly before you
  44. make most List Manager calls; drawing can occur in funny places if the
  45. grafPort is not set properly before calls that draw (like SelectMember2).
  46. Most List Manager calls, and many other toolbox calls, require that the
  47. current grafPort be explicitly set.  Before you call List Manager routines
  48. that draw, set the current port to your window with a SetPort call.  Remember
  49. the note in Volume 2 under the NewWindow call--"Important:  NewWindow does not
  50. set the current port, but many routines require that a current port exist.
  51. Use the QuickDraw II routine SetPort to set the current port."  Using SetPort
  52. can prevent toolbox confusion and reduce your debugging time.
  53.  
  54. DELETEMITEM OPERATES ON THE CURRENT MENU BAR
  55.  
  56. Page 13-37 says DeleteMItem removes the specified item from the current menu.
  57. It means the item is removed from the current menu bar.
  58.  
  59.  
  60. ERROR $0F02 FROM GETMITEM
  61.  
  62. GetMItem returns error $0F02 if the specified menu item is not found.
  63.  
  64. On page 13-45, the return value from GetMenuFlag should read "Word--menuFlag
  65. value for the specified menu."
  66.  
  67. On page 13-56, in the description of the hiliteFlag parameter to HiliteMenu,
  68. no particular value of "TRUE" is specified.  $0001 is a good value ($8000 does
  69. not work; bit 15 is special).
  70.  
  71. On page 13-72, SetMenuFlag doesn't bother to actually explain what it does.
  72. If bit 15 of newValue is zero, each set bit set forces the corresponding bit
  73. in the menu's flag value to be set.  If bit 15 of newValue is one, each clear
  74. bit forces the corresponding bit in the menu's flag value to be clear.
  75. Knowing this, you can set or clear more than one bit at a time, if you want.
  76.  
  77. SETVECTOR REFERENCE NUMBERS
  78.  
  79. On page 14-62, vector reference number $002C is listed as "Message pointer
  80. vector."  $002C is actually the stack-based GS/OS call vector.  (The real
  81. message pointer vector is not accessible through GetVector and SetVector.)
  82.  
  83. GETTING A CLEAN MOUSE MODE FROM READMOUSE
  84.  
  85. On ROM 3 computers, the mouse mode byte returned from ReadMouse sometimes has
  86. extra bits set in the high nibble.  Before feeding a ReadMouse value to
  87. SetMouse, mask off all but the low nibble (AND #$000F).
  88.  
  89. READASCIITIME RESULT BUFFER
  90.  
  91. The description of ReadAsciiTime (in the Miscellaneous Tools) on page 14-16
  92. should say the most significant bit (not byte) of each character is set to
  93. one.
  94.  
  95. SYSTEMEVENT IS ALL BACKWARDS
  96.  
  97. Although applications still should not call SystemEvent, we should note for
  98. completeness that the input parameters listed in Volume 1 are exactly
  99. backwards in the stack diagram.
  100.  
  101. CORRECTIONS TO VOLUME 2
  102.  
  103. QUICKDRAW AUXILIARY ERROR CODES
  104.  
  105. Following are some error codes from QuickDraw Auxiliary that are not listed in
  106. volume 2.
  107.  
  108.     $1210: picEmpty
  109.     $1211: picAlreadyOpen
  110.     $1212: pictureError
  111.  
  112.     $1221: badRect
  113.     $1222: badMode
  114.  
  115. FRAMERGN DOES NOT CONTRIBUTE TO AN OPEN REGION
  116.  
  117. The description of the FrameRgn routine on page 16-105 in the Apple IIgs
  118. Toolbox Reference, Volume 2 states that FrameRgn will contribute to a region
  119. definition if a region is open when FrameRgn is called.  This is incorrect;
  120. FrameRgn does not contribute to the region being defined.  To add a region to
  121. another region, use XorRgn or UnionRgn.
  122.  
  123. TOOL LOCATOR, TLMOUNTVOLUME
  124.  
  125. On page 24-21, the description of TLMountVolume does not bother to mention
  126. that QuickDraw II and Event Manager must be active.  If they are not, you
  127. should use TLTextMountVolume instead.
  128.  
  129. TOOL LOCATOR, SETTSPTR
  130.  
  131. When using SetTSPtr to patch a system tool set, the Tool Locator and Desk
  132. Manager are special.  See Apple IIgs Technical Note #101, Patching the
  133. Toolbox.
  134.  
  135. WINDOW MANAGER, "DRAW INFORMATION BAR ROUTINE"
  136.  
  137. On page 25-23, the code to clean up the stack is incorrect.  On the sta <14,
  138. the comment "Works because stack and direct page are equal" is no longer
  139. true--they were equal until the PLY two lines earlier.  One way to correct the
  140. code is to replace sta <14 with sta 14,s and sta <12 with sta 12,s.
  141.  
  142. WINDOW MANAGER, INVALRECT
  143.  
  144. The description of InvalRect on page 25-80 claims that InvalRect modifies the
  145. input rectangle; the rectangle is actually not modified.
  146.  
  147. WINDOW MANAGER, PINRECT
  148.  
  149. On page 25-89, in the description of PinRect, the two greater-than comparisons
  150. should be greater-than-or-equal.
  151.  
  152. WINDOW MANAGER, SETZOOMRECT
  153.  
  154. The description of SetZoomRect on page 25-112 refers to fZoomed as bit 2 in
  155. the window frame.  fZoomed is actually bit 1, with value $0002.
  156.  
  157. WINDOW RECORD OFFSETS
  158.  
  159. On page 25-142, note that the offsets given into the window record refer to
  160. the record as the Window Manager treats it internally, with a wNext field at
  161. the beginning.  When dealing with a window pointer as seen by an application,
  162. you need to subtract four from the offsets shown.  For example, wPort is $00
  163. (not $04), and wControls is $C6 (not $CA).
  164.  
  165. APPENDIX A, "WRITING YOUR OWN TOOL SETS"
  166.  
  167. At the bottom of page A-8, "lda #$90" should read "lda #$8100" for version 1.0
  168. prototype.
  169.  
  170. On page A-10, the figure should show two RTL addresses (6 bytes) on the stack.
  171.  
  172.  
  173. CORRECTIONS TO VOLUME 3
  174.  
  175. CONTROL MANAGER:  MENU EVENTS
  176.  
  177. On page 28-15, note that a Menu Event is identified by the value wInSpecial
  178. ($0019) in the what field of the task record.  The menu item ID is in the low
  179. word of the wmTaskData field.
  180.  
  181. CONTROL MANAGER:  DIMMED CUSTOM CONTROLS
  182.  
  183. In the Draw routine for both extended and non-extended controls, the high word
  184. of ctlParam (which was previously undocumented) contains a flag which the
  185. definition procedure can use to draw a normal or dimmed control.  The value is
  186. $0000 normally, but it is $FFFF when the control is inactive (hilite value
  187. equals $00FF), or when the control's state is tied to the window's state and
  188. the window is inactive.
  189.  
  190. CONTROL MANAGER:  SIZE BOX CONTROLS
  191.  
  192. The part code for an extended Size Box control is normally 10.  If the
  193. fCallWindowMgr bit is set in ctlFlag, the part code is $80; and if the size
  194. box is managed by a Text Edit control, the part code is $84.
  195.  
  196. When a Size Box control's fCallWindowMgr bit is set, the control needs to pass
  197. a minimum window size to GrowWindow.  It gets this value from its ctlData
  198. field, which you can get with GetCtlTitle and set with SetCtlTitle (the low
  199. word is the minimum height, and the high word is the minimum width).  A height
  200. of zero defaults to 50, and a width of zero defaults to 130.
  201.  
  202. DESK MANAGER:  ERRORS FROM ADDTORUNQ AND REMOVEFROMRUNQ
  203.  
  204. The Desk Manager chapter, page 29-6, states no errors are possible for
  205. AddToRunQ, but any errors from the Miscellaneous Tools routine AddToQueue are
  206. returned unchanged.
  207.  
  208. Page 29-8 states no errors are possible from RemoveFromRunQ, but any errors
  209. from DeleteFromQueue are returned unchanged.
  210.  
  211. EVENT MANAGER:  WHAT SETAUTOKEYLIMIT REALLY DOES
  212.  
  213. Page 31-6 says that PostEvent will add up to the new auto-key limit number of
  214. auto-key events before reverting to the rule that auto-key events are only to
  215. be posted if the event queue is empty.  This is not quite right.  Actually,
  216. the parameter to SetAutoKeyLimit is used in a size comparison on the event
  217. queue--if there are newLimit or more events in the queue, auto-key events will
  218. not be posted.  Volume 3 incorrectly states that up to newLimit auto-key
  219. events will be posted; this is only true if you assume the event queue is
  220. empty before the first auto-key event comes in.
  221.  
  222. LIST MANAGER
  223.  
  224. On page 35-9, the description of ResetMember2 does not point out an important
  225. difference between ResetMember2 and NextMember2.  ResetMember2 deselects the
  226. member found, but NextMember2 does not change the member's status.
  227.  
  228. On page 35-3, bit 5 of the memFlag field is defined--it makes an item
  229. inactive.  To make use of this bit, you must also set bit 6 of the List
  230. control's ctlFlag field; if you don't set this bit, the user will still be
  231. able to select members using the mouse.
  232.  
  233. MEMORY MANAGER
  234.  
  235. If the Memory Manager detects a corrupted entry in the Out Of Memory Queue,
  236. fatal system error $0209 occurs.
  237.  
  238. MENU MANAGER
  239.  
  240. On page 28-65, the description of the initialValue field is misleading.  Cross
  241. out the text "that is, its relative position within the array of items for the
  242. menu."  initialValue is simply a menu item ID, not an offset into an array.
  243.  
  244. Page 37-7 states "Because caching does not work with menus in windows, the
  245. InsertMenu call automatically disabled caching for such menus."  Actually,
  246. InsertMenu doesn't do that.  You should not set the allowCache bit for a menu
  247. in a window.
  248.  
  249. MISCELLANEOUS TOOLS:  INTERRUPT STATE RECORD NOT ALWAYS COMPLETE
  250.  
  251. The interrupt state record returned from GetInterruptState (and passed to
  252. SetInterruptState) is not always completely filled in.  The Interrupt Manager,
  253. in the interest of serving AppleTalk and serial interrupts as rapidly as
  254. possible, does not take the time to save all the items in the record until
  255. those timing-critical interrupt handlers have been called.  Some items are not
  256. saved at all unless the interrupt is determined to be a BRK instruction.
  257. Table 1 shows all items in the current interrupt state record and when they
  258. become valid:
  259.  
  260.        Record variable          When valid
  261.        -----------------------------------
  262.         irq_A                always
  263.         irq_X                always
  264.         irq_Y                always
  265.         irq_S                after serial
  266.         irq_D                always
  267.         irq_P                only on break
  268.         irq_DB               after serial
  269.         irq_e                after serial
  270.         irq_K                only on break
  271.         irq_PC               only on break
  272.         irq_state            after serial
  273.         irq_shadow           always
  274.         irq_mslot            after serial
  275.        ------------------------------------
  276.       Table 1--Validity of Interrupt Record
  277.  
  278.  
  279. STANDARD FILE
  280.  
  281. On page 48-39, the description of origNameRef reads "On output, this string
  282. contains the string confirmed by the user, which may not be the same length as
  283. the default value."  This sentence is confused; ignore it.  The string is not
  284. changed at all; Standard File doesn't even know how long the buffer is.
  285.  
  286. TOOL LOCATOR:  NOTES ON STARTUPTOOLS
  287.  
  288. StartUpTools in System Software 5.0.4 and earlier is intended to be used from
  289. applications only, not from NDAs.
  290.  
  291. The order of the toolArray entries in the StartStop record is not important.
  292. StartUpTools and ShutDownTools always start up and shut down tools in a
  293. correct order.
  294.  
  295. StartUpTools in System Software 5.0.4 and earlier fails to open your
  296. application's resource fork if the application's filename contains a slash (/)
  297. or if the application directory path is longer than 64 characters.
  298.  
  299. For maximum compatibility, pass your application's master user ID with any
  300. auxID to StartUpTools instead of allocating a new user ID.
  301.  
  302. WINDOW MANAGER:NEWWINDOW2 PARAMETERS OVERRIDE TEMPLATE EVEN WHEN YOU PASS NIL
  303.  
  304. The description of the NewWindow2 call on page 52-32 is in error.  The
  305. description of the titlePtr, refCon, contentDrawPtr, and defProcPtr says, "To
  306. prevent NewWindow2 from replacing the template values, supply NIL pointers..."
  307. This is only  true for the titlePtr parameter--if you pass NIL for any of the
  308. other parameters then the value of that parameter in your window record is
  309. also NIL, no matter what the template value was.  In other words, if you have
  310. the value $99 stored in your template refCon field, and you pass NIL for the
  311. refCon value in a NewWindow2 call, the value of the refCon in the returned
  312. grafPortPtr is NIL.
  313.  
  314. APPENDIX E:  RTEXTFORLETEXTBOX2 RESOURCES
  315.  
  316. Page E-68 of Volume 3 shows a length field at the beginning of an
  317. rTextForLETextBox2 resource. This field is not actually present.  The length
  318. is simply the size of the resource--it is not stored redundantly.
  319.  
  320. APPENDIX E:  RTWORECTS RESOURCES
  321.  
  322. When the two rectangles are for 320- and 640-mode, by convention the rectangle
  323. for 320 mode comes first.
  324.  
  325.  
  326. Further Reference:
  327. _____________________________________________________________________________
  328.  
  329.    o   Apple IIgs Toolbox Reference, Volumes 1-3
  330.    o   Apple IIgs Technical Note #101, Patching the Toolbox
  331.